<?xml version="1.0" encoding="ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>robotide.pluginapi</title>
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
  <script type="text/javascript" src="epydoc.js"></script>
</head>

<body bgcolor="white" text="black" link="blue" vlink="#204080"
      alink="#204080">
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="robotide-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            ><a class="navbar" target="_top" href="http://code.google.com/p/robotframework-ride">RIDE</a></th>
          </tr></table></th>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
  <tr valign="top">
    <td width="100%">
      <span class="breadcrumbs">
        <a href="robotide-module.html">Package&nbsp;robotide</a> ::
        Package&nbsp;pluginapi
      </span>
    </td>
    <td>
      <table cellpadding="0" cellspacing="0">
        <!-- hide/show private -->
      </table>
    </td>
  </tr>
</table>
<!-- ==================== PACKAGE DESCRIPTION ==================== -->
<h1 class="epydoc">Package pluginapi</h1><p class="nomargin-top"><span class="codelink"><a href="robotide.pluginapi-pysrc.html">source&nbsp;code</a></span></p>
<p>RIDE Plugin API</p>
<div class="rst-contents rst-local rst-topic" id="rst-contents">
<ul class="rst-simple">
<li><a class="rst-reference internal" href="#rst-introduction" id="rst-id1">Introduction</a></li>
<li><a class="rst-reference internal" href="#rst-finding-plugins" id="rst-id2">Finding plugins</a></li>
<li><a class="rst-reference internal" href="#rst-initialization" id="rst-id3">Initialization</a></li>
<li><a class="rst-reference internal" href="#rst-enabling-and-disabling" id="rst-id4">Enabling and disabling</a></li>
<li><a class="rst-reference internal" href="#rst-creating-menu-entries-and-shortcuts" id="rst-id5">Creating menu entries and shortcuts</a></li>
<li><a class="rst-reference internal" href="#rst-messaging" id="rst-id6">Messaging</a></li>
<li><a class="rst-reference internal" href="#rst-settings" id="rst-id7">Settings</a></li>
</ul>
</div>
<div class="rst-section" id="rst-introduction">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id1">Introduction</a></h1>
<p>RIDE can be extended with plugins written in Python starting with version 0.16.
The plugin API went through a major overhaul in the 0.20 release and this
documentation describes how to write plugins against the new API. After the
changes in RIDE 0.20, the goal is to limit backwards incompatible changes to
the minimum at least until the 1.0 release sometime in the spring 2010.</p>
</div>
<div class="rst-section" id="rst-finding-plugins">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id2">Finding plugins</a></h1>
<p>Plugins are loaded automatically when RIDE starts up. RIDE will look in the
following directories for plugins:</p>
<ul class="rst-simple">
<li><tt class="rst-docutils literal"><span class="pre">&lt;RIDE_INSTALLATION_DIR&gt;/site-plugins</span></tt></li>
<li><tt class="rst-docutils literal"><span class="pre">&lt;USER_DATA&gt;/plugins</span></tt></li>
</ul>
<p>Location of the <tt class="rst-docutils literal">&lt;USER_DATA&gt;</tt> directory will vary depending on your platform.
On Linux and OSX this will be <tt class="rst-docutils literal"><span class="pre">~/.robotframework/ride</span></tt> while on Windows the
location is <tt class="rst-docutils literal"><span class="pre">%APPDATA%\RobotFramework\ride</span></tt>.</p>
<p>Each Python file that is found in these directories is dynamically imported and
inspected. Every subclass of the <a href="robotide.pluginapi.plugin.Plugin-class.html" class="link">Plugin</a> class in these files will be
instantiated as a plugin. This has a few noteworthy consequences:</p>
<ul class="rst-simple">
<li>Common utility code may be distributed as separate files, located in the
plugin directories.</li>
<li>All the top level code in the found Python files is executed as they are
imported. Beware of the side effects.</li>
<li>A Python file may contain more than one plugin.</li>
</ul>
</div>
<div class="rst-section" id="rst-initialization">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id3">Initialization</a></h1>
<p>As stated earlier, every plugin <em>must</em> inherit from the <a href="robotide.pluginapi.plugin.Plugin-class.html" class="link">Plugin</a> base class.
This class is exposed directly from the <a href="robotide.pluginapi-module.html" class="link">pluginapi</a> module, similarly as all
other classes that plugins most often need, and can thus be imported like:</p>
<pre class="rst-literal-block">
from robotide.pluginapi import Plugin
</pre>
<p>When a plugin class is found, an instance of it will be created. Different
initialization options are explained in the documentation of the
<a href="robotide.pluginapi.plugin.Plugin-class.html#__init__" class="link">Plugin.__init__</a> method. If creating an instance of a plugin class fails, an
error message is shown to the user and the plugin is disabled.</p>
</div>
<div class="rst-section" id="rst-enabling-and-disabling">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id4">Enabling and disabling</a></h1>
<p>Plugins can control are they enabled by default when they are loaded for the
first time. Afterwards users can enable and disable plugins from the plugin
manager, which is available from the menu through <tt class="rst-docutils literal">Tools &gt; Manage Plugins</tt>.
Plugins' enabled/disabled state is stored into RIDE's settings file and read
from there when plugins are loaded again later.</p>
<p>When the plugin is enabled, the <a href="robotide.pluginapi.plugin.Plugin-class.html#enable" class="link">Plugin.enable</a> method is called. This is the
point where the plugin is actually turned on and also the time when possible
integration into RIDE UI should happen. The <a href="robotide.pluginapi.plugin.Plugin-class.html#disable" class="link">Plugin.disable</a> method is called
when the plugin is disabled, and its purpose is to undo whatever was done in
the <a href="robotide.pluginapi.plugin.Plugin-class.html#enable" class="link">Plugin.enable</a> method.</p>
</div>
<div class="rst-section" id="rst-creating-menu-entries-and-shortcuts">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id5">Creating menu entries and shortcuts</a></h1>
<p>Plugins can create new entries to menus, buttons to the toolbar, and register
shortcuts using <a href="robotide.action.actioninfo.ActionInfo-class.html" class="link">ActionInfo</a> objects and the <a href="robotide.pluginapi.plugin.Plugin-class.html#register_action" class="link">Plugin.register_action</a> method.
Registering actions is thoroughly documented in the <a href="robotide.action-module.html" class="link">robotide.action</a> module.
Notice that all the relevant action classes are exposed also through the
<a href="robotide.pluginapi-module.html" class="link">pluginapi</a> module and plugins should import them like:</p>
<pre class="rst-literal-block">
from robotide.pluginapi import ActionInfo
</pre>
</div>
<div class="rst-section" id="rst-messaging">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id6">Messaging</a></h1>
<p>RIDE has a messaging system that allows both sending messages when something
happens and subscribing to certain messages. Messages sent upon some
user action, like selecting an item in the tree or saving a file, are the
main communication mechanism from RIDE to plugins, but sometimes plugins may
also have a need to sent their own messages. Plugins can subscribe to messages
using the <a href="robotide.pluginapi.plugin.Plugin-class.html#subscribe" class="link">Plugin.subscribe</a> method. The whole messaging system is documented
in the <a href="robotide.publish-module.html" class="link">robotide.publish</a> module, but plugins can import the relevant classes
through the <a href="robotide.pluginapi-module.html" class="link">pluginapi</a> module like:</p>
<pre class="rst-literal-block">
from robotide.pluginapi import RideTreeSelection, RideSaved
</pre>
</div>
<div class="rst-section" id="rst-settings">
<h1 class="heading"><a class="rst-toc-backref" href="#rst-id7">Settings</a></h1>
<p>Plugin can store information persistently to RIDE's setting file. The initial
values can be given to the <a href="robotide.pluginapi.plugin.Plugin-class.html#__init__" class="link">Plugin.__init__</a> method and new values saved using
<a href="robotide.pluginapi.plugin.Plugin-class.html#save_setting" class="link">Plugin.save_setting</a>. Saved settings can be accessed using direct attribute
access via <a href="robotide.pluginapi.plugin.Plugin-class.html#__getattr__" class="link">Plugin.__getattr__</a>.</p>
<p>Settings are stored into the setting file under <tt class="rst-docutils literal">[Plugins]</tt> section into
plugin specific subsections. Settings names starting with an underscore
(currently only <tt class="rst-docutils literal">_enabled</tt>) are reserved for RIDE's internal usage. The saved
settings may look something like this:</p>
<pre class="rst-literal-block">
[Plugins]
[[Release Notes]]
version_shown = 'trunk'
_enabled = True
[[Recent Files]]
max_number_of_files = 4
recent_files = []
_enabled = False
</pre>
</div>

<!-- ==================== SUBMODULES ==================== -->
<a name="section-Submodules"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Submodules</span></td>
</tr>
  <tr><td class="summary">
  <ul class="nomargin">
    <li> <strong class="uidlink"><a href="robotide.pluginapi.plugin-module.html">robotide.pluginapi.plugin</a></strong>    </li>
  </ul></td></tr>
</table>

<br />
<!-- ==================== VARIABLES ==================== -->
<a name="section-Variables"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Variables</span></td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="robotide.pluginapi-module.html#__package__" class="summary-name">__package__</a> = <code title="'robotide.pluginapi'"><code class="variable-quote">'</code><code class="variable-string">robotide.pluginapi</code><code class="variable-quote">'</code></code>
    </td>
  </tr>
</table>
<p class="indent-wrapped-lines"><b>Imports:</b>
  <a href="robotide.action.actioninfo-module.html#ActionInfoCollection" title="robotide.action.ActionInfoCollection">ActionInfoCollection</a>,
  <a href="robotide.action.actioninfo.ActionInfo-class.html" title="robotide.action.ActionInfo">ActionInfo</a>,
  <a href="robotide.action.actioninfo.SeparatorInfo-class.html" title="robotide.action.SeparatorInfo">SeparatorInfo</a>,
  <a href="robotide.pluginapi.plugin.Plugin-class.html" title="robotide.pluginapi.plugin.Plugin">Plugin</a>,
  <a href="robotide.publish.messages.RideChangeFormat-class.html" title="robotide.publish.messages.RideChangeFormat">RideChangeFormat</a>,
  <a href="robotide.publish.messages.RideClosing-class.html" title="robotide.publish.messages.RideClosing">RideClosing</a>,
  <a href="robotide.publish.messages.RideDataChangedToDirty-class.html" title="robotide.publish.messages.RideDataChangedToDirty">RideDataChangedToDirty</a>,
  <a href="robotide.publish.messages.RideDataDirtyCleared-class.html" title="robotide.publish.messages.RideDataDirtyCleared">RideDataDirtyCleared</a>,
  <a href="robotide.publish.messages.RideDataFileRemoved-class.html" title="robotide.publish.messages.RideDataFileRemoved">RideDataFileRemoved</a>,
  <a href="robotide.publish.messages.RideGridCellChanged-class.html" title="robotide.publish.messages.RideGridCellChanged">RideGridCellChanged</a>,
  <a href="robotide.publish.messages.RideImportSetting-class.html" title="robotide.publish.messages.RideImportSetting">RideImportSetting</a>,
  <a href="robotide.publish.messages.RideImportSettingAdded-class.html" title="robotide.publish.messages.RideImportSettingAdded">RideImportSettingAdded</a>,
  <a href="robotide.publish.messages.RideImportSettingChanged-class.html" title="robotide.publish.messages.RideImportSettingChanged">RideImportSettingChanged</a>,
  <a href="robotide.publish.messages.RideImportSettingRemoved-class.html" title="robotide.publish.messages.RideImportSettingRemoved">RideImportSettingRemoved</a>,
  <a href="robotide.publish.messages.RideInitFileRemoved-class.html" title="robotide.publish.messages.RideInitFileRemoved">RideInitFileRemoved</a>,
  <a href="robotide.publish.messages.RideItem-class.html" title="robotide.publish.messages.RideItem">RideItem</a>,
  <a href="robotide.publish.messages.RideItemNameChanged-class.html" title="robotide.publish.messages.RideItemNameChanged">RideItemNameChanged</a>,
  <a href="robotide.publish.messages.RideItemSettingsChanged-class.html" title="robotide.publish.messages.RideItemSettingsChanged">RideItemSettingsChanged</a>,
  <a href="robotide.publish.messages.RideItemStepsChanged-class.html" title="robotide.publish.messages.RideItemStepsChanged">RideItemStepsChanged</a>,
  <a href="robotide.publish.messages.RideLog-class.html" title="robotide.publish.messages.RideLog">RideLog</a>,
  <a href="robotide.publish.messages.RideLogException-class.html" title="robotide.publish.messages.RideLogException">RideLogException</a>,
  <a href="robotide.publish.messages.RideLogMessage-class.html" title="robotide.publish.messages.RideLogMessage">RideLogMessage</a>,
  <a href="robotide.publish.messages.RideMessage-class.html" title="robotide.publish.messages.RideMessage">RideMessage</a>,
  <a href="robotide.publish.messages.RideNewProject-class.html" title="robotide.publish.messages.RideNewProject">RideNewProject</a>,
  <a href="robotide.publish.messages.RideNotebookTabChanged-class.html" title="robotide.publish.messages.RideNotebookTabChanged">RideNotebookTabChanged</a>,
  <a href="robotide.publish.messages.RideNotebookTabChanging-class.html" title="robotide.publish.messages.RideNotebookTabChanging">RideNotebookTabChanging</a>,
  <a href="robotide.publish.messages.RideOpenResource-class.html" title="robotide.publish.messages.RideOpenResource">RideOpenResource</a>,
  <a href="robotide.publish.messages.RideOpenSuite-class.html" title="robotide.publish.messages.RideOpenSuite">RideOpenSuite</a>,
  <a href="robotide.publish.messages.RideSaveAll-class.html" title="robotide.publish.messages.RideSaveAll">RideSaveAll</a>,
  <a href="robotide.publish.messages.RideSaved-class.html" title="robotide.publish.messages.RideSaved">RideSaved</a>,
  <a href="robotide.publish.messages.RideSaving-class.html" title="robotide.publish.messages.RideSaving">RideSaving</a>,
  <a href="robotide.publish.messages.RideSelectResource-class.html" title="robotide.publish.messages.RideSelectResource">RideSelectResource</a>,
  <a href="robotide.publish.messages.RideSettingsChanged-class.html" title="robotide.publish.messages.RideSettingsChanged">RideSettingsChanged</a>,
  <a href="robotide.publish.messages.RideSuiteAdded-class.html" title="robotide.publish.messages.RideSuiteAdded">RideSuiteAdded</a>,
  <a href="robotide.publish.messages.RideTestCaseAdded-class.html" onclick="show_private();" title="robotide.publish.messages.RideTestCaseAdded">RideTestCaseAdded</a>,
  <a href="robotide.publish.messages.RideTestCaseRemoved-class.html" title="robotide.publish.messages.RideTestCaseRemoved">RideTestCaseRemoved</a>,
  <a href="robotide.publish.messages.RideTreeSelection-class.html" title="robotide.publish.messages.RideTreeSelection">RideTreeSelection</a>,
  <a href="robotide.publish.messages.RideUserKeyword-class.html" title="robotide.publish.messages.RideUserKeyword">RideUserKeyword</a>,
  <a href="robotide.publish.messages.RideUserKeywordAdded-class.html" title="robotide.publish.messages.RideUserKeywordAdded">RideUserKeywordAdded</a>,
  <a href="robotide.publish.messages.RideUserKeywordRemoved-class.html" title="robotide.publish.messages.RideUserKeywordRemoved">RideUserKeywordRemoved</a>,
  <a href="robotide.publish.messages.RideVariableAdded-class.html" title="robotide.publish.messages.RideVariableAdded">RideVariableAdded</a>,
  <a href="robotide.publish.messages.RideVariableMovedDown-class.html" title="robotide.publish.messages.RideVariableMovedDown">RideVariableMovedDown</a>,
  <a href="robotide.publish.messages.RideVariableMovedUp-class.html" title="robotide.publish.messages.RideVariableMovedUp">RideVariableMovedUp</a>,
  <a href="robotide.publish.messages.RideVariableRemoved-class.html" title="robotide.publish.messages.RideVariableRemoved">RideVariableRemoved</a>,
  <a href="robotide.publish.messages.RideVariableUpdated-class.html" title="robotide.publish.messages.RideVariableUpdated">RideVariableUpdated</a>,
  <a href="robotide.pluginapi.plugin-module.html" title="robotide.pluginapi.plugin">plugin</a>
</p><br />
<!-- ==================== VARIABLES DETAILS ==================== -->
<a name="section-VariablesDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Variables Details</span></td>
</tr>
</table>
<a name="__package__"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <h3 class="epydoc">__package__</h3>
  
  <dl class="fields">
  </dl>
  <dl class="fields">
    <dt>Value:</dt>
      <dd><table><tr><td><pre class="variable">
<code class="variable-quote">'</code><code class="variable-string">robotide.pluginapi</code><code class="variable-quote">'</code>
</pre></td></tr></table>
</dd>
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="robotide-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            ><a class="navbar" target="_top" href="http://code.google.com/p/robotframework-ride">RIDE</a></th>
          </tr></table></th>
  </tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
  <tr>
    <td align="left" class="footer">
    Generated by Epydoc 3.0.1 on Wed Apr 13 15:09:36 2011
    </td>
    <td align="right" class="footer">
      <a target="mainFrame" href="http://epydoc.sourceforge.net"
        >http://epydoc.sourceforge.net</a>
    </td>
  </tr>
</table>

<script type="text/javascript">
  <!--
  // Private objects are initially displayed (because if
  // javascript is turned off then we want them to be
  // visible); but by default, we want to hide them.  So hide
  // them unless we have a cookie that says to show them.
  checkCookie();
  // -->
</script>
</body>
</html>
